Adjusting Dashes to Fit Contours (IM: XG)

Inside Macintosh: QuickDraw GX Graphics /: Chapter 3 - Geometric Styles / Using Geometric Styles

Adjusting Dashes to Fit Contours
Sometimes the dash advance does not divide evenly into the length of a contour and the dashes don't look quite right. QuickDraw GX provides the auto-advance dash attribute (gxAutoAdvanceDash) to handle this situation.
For example, the sample function in Listing 3-14 creates a circle dashed with kite-shaped diamonds. It does not use the auto-advance dash attribute.
Listing 3-14 Creating a dashed circle
void CreateDashedCircle(void)
{
   gxShape  aCircleShape, aDiamondShape;

   static gxRectanglecircleBounds = {ff(50), ff(50), 
                                     ff(180), ff(180)};
   
   static long diamondGeometry[] = {1, /* number of contours */
                                    4, /* number of points */
                                    ff(0), ff(20), 
                                    ff(15), ff(0),
                                    ff(0), -ff(40), 
                                    -ff(15), ff(0)};
      
   gxDashRecord theDashRecord;
   
   
   aCircleShape = NewArc(&circleBounds, ff(0), ff(360), false);
   GXSetShapeFill(aCircleShape, gxHollowFill);

   aDiamondShape = GXNewPolygons((gxPolygons *) diamondGeometry);
      
   theDashRecord.attributes = gxNoAttributes;  
   theDashRecord.dash = aDiamondShape;
   theDashRecord.advance = ff(30); 
   theDashRecord.phase = 0; 
   theDashRecord.scale = ff(60); 

   GXSetShapeDash(aCircleShape, &theDashRecord);
   
   GXDisposeShape(aDiamondShape);
      
   GXSetShapePen(aCircleShape, ff(60));
   
   GXDrawShape(aCircleShape);
}
Since this sample function does not set the auto-advance dash attribute, and the dash advance of 30 does not divide evenly into the circumference of the circle, this function results in the shape shown in Figure 3-63.
Figure 3-63 Circle dashed with diamonds

Notice that the initial dash and the final dash overlap. (The overlapping region is not filled, because, by default, the dash shape has winding shape fill.)
If, however, you set the auto-advance dash attribute, using this line of code:
theDashRecord.attributes = gxAutoAdvanceDash;  
QuickDraw GX adjusts the dash advance accordingly. The result is shown in Figure 3-64.
Figure 3-64 Circle with automatically advanced dashes

As you can see, QuickDraw GX adjusts the dash advance the smallest amount possible to create a whole number of dashes along the contour.
The sections "The Dash Structure" on page 3-103 and "Dash Attributes" on page 3-105 describe the dash structure and dash attributes in more detail, and the section "Getting and Setting Dashes" beginning on page 3-134 describes the functions you can use to manipulate dashes.